Static content review: site + wiki fixes from dual design review - #2
Merged
Conversation
Linkified citation spine into /design/, OG/Twitter/canonical metadata + social card, status-note honesty + as-of date, token fixes (bg-note-status, hue drift), <picture> theme swap, a11y fixes (tabindex, target size, en-GB, permalinks), 404/robots/sitemap, favicon consolidation, deploy gates (html-validate + offline linkcheck), design-skill safe subset. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
… as repo script Diagrams re-rendered with the system font stack through tools/diagrams/theme-site-*.json (0/35 node overflow under four substituted fonts); render.sh rationale rewritten to match. Social card renamed to og-card, status note drops the hard-coded findings count. Link gate restored to tools/ci/linkcheck.py, called from the workflow. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Edit-URI hook (44 resolve, 8 suppressed, 0 broken), canonical nav ordering from 00-INDEX + §13.x scrape, diagram frames with full-size links and injected dark variants gated by DIAGRAM_PALETTE, material/search with CamelCase separator, SRI+defer for pinned CDN deps (privacy plugin rejected: MathJax font paths), domain heading normalisation (396 anchors unchanged), section index pages, contrast fixes, version-drift guard, staging hardening (comment masking, ~~~ fences, front-matter warning). Mark staged from site/assets/mark.svg; wiki→site home link. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Round 1: html-validate pinned @11, wiki cache key widened to mkdocs.yml+requirements.txt, linkcheck root containment / quote-agnostic id regex / srcset candidates / same-origin absolutes, og-card source excluded from the artifact, design-skill manifest divergence recorded in the readme. Round 2: scheme filter before splitting (data: URIs no longer shatter, srcset-only comma handling), content= og/twitter coverage by SELF_ORIGINS value. Gate verdict: all findings ADDRESSED, stream closed; 18/18 injection suite. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
C-1: diagram_figure emits markdown-in-HTML (markdown=span figures, block markdown on figure and details wrappers) so mkdocs rewrites asset paths; all 20 diagrams and full-size links now resolve, verified in-browser both schemes. New check_links.py wired into build.sh gates every src/href/srcset in the built HTML (3730 URLs) — the raw-HTML class --strict cannot see. C-2: mathjax-config clearCache?.() — the CHTML-only call threw under the SVG jax and killed re-typesetting on instant navigation. I-1: local _relink() rebuilds nav.pages + prev/next/parent after on_nav sort, so the footer walks canonical order. I-2: announce-bar contrast fixed via .md-banner-scoped selectors (specificity, not tokens; 9.70:1/10.85:1 both schemes) + edit-pencil contrast. m-1/m-2: section classification and edit remaps derived from the staged tree via nav-order.json. m-3: frames keyboard-scrollable. Note: b847980's message misdescribes its own M6 — the shipped approach was material/privacy + tex-mml-svg (fully vendored, zero third-party requests), not SRI+defer; the message was written from a superseded interim report. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
There was a problem hiding this comment.
Pull request overview
Updates Simic’s static publishing surfaces (hand-written marketing site at / and the MkDocs-generated design wiki at /design/) to incorporate design-review findings, improve accessibility/SEO, and add stronger pre-deploy validation gates so broken links/anchors don’t ship.
Changes:
- Strengthen wiki staging and MkDocs behavior (canonical nav ordering, correct “edit this page” links, generated section index pages, diagram framing/palette gating).
- Improve marketing site metadata + UX (OG/Twitter/canonical tags, sitemap/robots/404, heading permalinks, scrollable containers,
<picture>theme swap to avoid double-fetching diagram SVGs). - Add new CI and local gates for static output correctness (HTML validation + offline link/fragment checking).
Reviewed changes
Copilot reviewed 24 out of 33 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
tools/wiki/stage.py |
Expands staging transforms, generates nav-order metadata, adds diagram framing/palette checks, and normalizes headings/section landing pages. |
tools/wiki/README.md |
Documents stricter build behavior, link validation expectations, and how hooks/staging work. |
tools/wiki/overrides/main.html |
Adds an announce-bar “way back” link from the wiki to the marketing site. |
tools/wiki/mkdocs.yml |
Enables navigation.indexes, switches to Material search with CamelCase separator, adds privacy vendoring, and wires hooks. |
tools/wiki/hooks.py |
New MkDocs hooks to fix edit-link targets and enforce canonical nav + prev/next ordering. |
tools/wiki/check_links.py |
New post-build gate to verify local href/src/srcset in built HTML resolve to real output files. |
tools/wiki/build.sh |
Adds version-pin enforcement and runs the new wiki HTML link gate after mkdocs build. |
tools/wiki/assets/simic.css |
Improves contrast tokens and styles the new upbar + diagram “light plate” frames + icon visibility fixes. |
tools/wiki/assets/mathjax-config.js |
Fixes instant-navigation MathJax behavior by guarding clearCache for SVG output. |
tools/diagrams/theme-site-light.json |
Updates Mermaid theme font stack to match site typography. |
tools/diagrams/theme-site-dark.json |
Updates Mermaid theme font stack to match site typography. |
tools/diagrams/render.sh |
Documents font-stack change rationale and updates site-diagram dimension check messaging. |
tools/ci/linkcheck.py |
New offline link + fragment validator for the assembled Pages artifact (marketing ↔ wiki deep-link seam). |
site/style.css |
Improves tokens, adds heading permalinks + citation styling, switches diagram theming to <picture>, and a11y/print tweaks. |
site/sitemap.xml |
Adds a hand-maintained sitemap for the three marketing pages. |
site/robots.txt |
Adds robots rules and advertises both marketing + wiki sitemaps. |
site/lineage.html |
Adds metadata, permalinks, updated citations into /design/, and minor content/UX/a11y adjustments. |
site/index.html |
Adds metadata, project-status note update, permalinks, <picture> diagrams, and wiki deep links. |
site/assets/og-card.src.html |
Adds reproducible source for generating the Open Graph card PNG. |
site/assets/mark.svg |
Introduces a shared SVG brand mark used as favicon/logo. |
site/assets/diagrams/observation-loop-light.svg |
Re-renders a diagram SVG (font stack/geometry update). |
site/architecture.html |
Adds metadata, permalinks, updated citations into /design/, <picture> diagrams, and a11y tweaks. |
site/404.html |
Adds a root-site 404 page appropriate for GitHub Pages behavior. |
.gitignore |
Ignores prompts/ directory. |
.github/workflows/deploy-site.yml |
Expands cache key inputs and adds pre-upload validation gates (html-validate + link/fragment checking). |
.claude/skills/simic-design/styles.css |
Flattens previously-import-based design-token stylesheet into an in-repo token-only source. |
.claude/skills/simic-design/readme.md |
Updates design-skill documentation to reflect current theming/diagram behavior and export-state notes. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| localStorage flag, and this is navigation, not an announcement. | ||
| -#} | ||
| {% block announce %} | ||
| <a class="simic-upbar" href="https://simic.foundryside.dev/"> |
Comment on lines
+83
to
+101
| def resolves(page: Path, url: str, base: str) -> Path | None: | ||
| """The file a URL points at, or None if it is not ours to check.""" | ||
| if not url or url.startswith("#") or EXTERNAL.match(url): | ||
| return None | ||
| path = unquote(urlsplit(url).path) | ||
| if not path: | ||
| return None | ||
| if path.startswith("/"): | ||
| # Root-absolute: relative to the deployment root, so drop the mount | ||
| # prefix. A root-absolute URL OUTSIDE our mount belongs to the other | ||
| # half of the site and is not ours to verify. | ||
| if base and not (path == base or path.startswith(base + "/")): | ||
| return None | ||
| target = SITE / path[len(base) :].lstrip("/") | ||
| else: | ||
| target = page.parent / path | ||
| target = Path(target).resolve() | ||
| # A directory URL is served by its index.html. | ||
| return target / "index.html" if url.endswith("/") or target.is_dir() else target |
Comment on lines
+496
to
+500
| # so in dark mode it reads as a printed figure laid on the page rather than as | ||
| # a lighting bug. No colour in the export is altered, which is why this is the | ||
| # option that ships: a recoloured variant cannot be signed off without looking | ||
| # at it, and no browser was available during this work. | ||
| # |
|
|
||
| There is **no icon system**. The site ships zero icon fonts, zero icon SVG sets. The complete iconography: | ||
| - **The mark**: a teal diamond (`assets/mark.svg`, `#0f9b8e`), used as favicon and rendered as the `◈` character before the wordmark (`.wordmark::before`, colored accent). This is the closest thing to a logo — there is no wordmark image; the wordmark is live text in mono. | ||
| - **The mark**: a teal diamond, used as favicon and rendered as the `◈` character before the wordmark (`.wordmark::before`, colored accent). This is the closest thing to a logo — there is no wordmark image; the wordmark is live text in mono. One file, two deployed copies kept byte-identical: `site/assets/mark.svg` (marketing) and `tools/wiki/assets/mark.svg` (wiki logo + favicon). Its `#0f9b8e` is a fixed hex, not a token — a favicon cannot use `light-dark()` — and sits between `--teal-600` and `--teal-400`; do not introduce a fourth teal to match it. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Implements the findings of a two-stream design review of the static content (marketing site + design-docs wiki), each stream implemented and then closed by an independent adversarial review gate with browser verification.
Marketing site (
site/, deploy workflow, design-skill subset)/design/deep links (16 targets, anchor-verified); OG/Twitter/canonical metadata + 1200×630 social card; honest dated status note--color-bg-note-status, hue drift),<picture>-based theme swap (halves SVG payload), diagrams re-rendered in the system font stack (0/35 clipped under 5 substituted fonts)en-GB, heading permalinks;404.html/robots.txt/sitemap.xmlhtml-validate@11+tools/ci/linkcheck.py(every internal link and fragment of the assembled artifact; 18/18 injection test suite)Wiki (
tools/wiki/)clearCache?.())material/privacyvendoring, network-log verified)check_links.py(3,730 URLs — the raw-HTML class--strictcannot see) and a diagram palette checkAccepted deferrals are recorded in the review reports and the design-skill readme (border non-text contrast; generated manifest divergence with its re-sync checklist).
Test plan
./tools/wiki/build.shstrict + link gate: exit 0, 53 pages, 3,730 URLs resolve_pagesassembly through both new gates locally: exit 0wardline scan . --fail-on ERROR: passed🤖 Generated with Claude Code